{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "%pylab inline\n",
    "import matplotlib.pylab as pylab\n",
    "pylab.rcParams['figure.figsize'] = 16, 8  # that's default image size for this interactive session"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# TimeSide API"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "*Timeside* API is based on different core processing unit called *processors* :\n",
    "\n",
    "- Decoders (*timeside.api.IDecoder*) that enables to decode a giving audio source and split it up into frames for further processing\n",
    "- Analyzers (*timeside.api.IAnalyzer*) that provides some signal processing module to analyze incoming audio frames\n",
    "- Encoders (*timeside.api.IEncoder*) that can encode incoming frames back into an audio object\n",
    "- Graphers (*timeside.api.IGrapher*) that can display some representations of the signal or corresponding extracted features"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Decoders"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "\n",
    "import timeside.core\n",
    "\n",
    "from timeside.core import list_processors\n",
    "\n",
    "list_processors(timeside.core.api.IDecoder)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Analyzers"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "list_processors(timeside.core.api.IAnalyzer)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Encoders"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "list_processors(timeside.core.api.IEncoder)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Graphers"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "list_processors(timeside.core.api.IGrapher)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Processors pipeline"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "All these processors can be chained to form a process pipeline.\n",
    "\n",
    "Let first define a decoder that reads and decodes audio from a file"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "from timeside.core import get_processor\n",
    "\n",
    "from timeside.core.tools.test_samples import samples\n",
    "file_decoder = get_processor('file_decoder')(samples['C4_scale.wav'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And then some other processors"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "# analyzers\n",
    "pitch = get_processor('aubio_pitch')()\n",
    "level = get_processor('level')()\n",
    "\n",
    "# Encoder\n",
    "mp3 = get_processor('mp3_encoder')('/tmp/guitar.mp3', overwrite=True)\n",
    "\n",
    "# Graphers\n",
    "specgram = get_processor('spectrogram_lin')()\n",
    "waveform = get_processor('waveform_simple')()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's now define a process pipeline with all these processors and run it"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "pipe = (file_decoder | pitch | level | mp3 | specgram | waveform)\n",
    "pipe.run()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Analyzers results are available through the pipe:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "pipe.results.keys()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "or from the analyzer:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "pitch.results.keys()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "pitch.results['aubio_pitch.pitch'].keys()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "pitch.results['aubio_pitch.pitch']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Grapher result can also be display or save into a file"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "imshow(specgram.render(), origin='lower')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "imshow(waveform.render(), origin='lower')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "waveform.render('/tmp/waveform.png')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## And TimeSide can be embedded into a web page dynamically. For example, in Telemeta:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "from IPython.display import HTML\n",
    "HTML('<iframe width=1300 height=260 frameborder=0 scrolling=no marginheight=0 marginwidth=0 src=http://demo.telemeta.org/archives/items/6/player/1200x170></iframe>')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 2",
   "language": "python",
   "name": "python2"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 2
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython2",
   "version": "2.7.12"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}
